home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / edit / xvidoc.zip / SOURCE.MS < prev    next >
Text File  |  1992-07-28  |  44KB  |  1,414 lines
  1. .\"========== Redefine NH to avoid widowing
  2. .rn NH Nh
  3. .nr nH 0
  4. .de NH
  5. .br
  6. .if \\n(nH=\\$1 .sp 0.3i
  7. .nr nH 1
  8. .ne 1i
  9. .Nh \\$1 \\$2
  10. ..
  11. .\"========== Example macros
  12. .de Ex
  13. .br
  14. .ne 0.75i
  15. .IP "\fB\\$1\fP\ \ \ " \\$2
  16. ..
  17. .de Ey
  18. .sp -0.3v
  19. .IP "\fB\\$1\fP\ \ \ " \\$2
  20. ..
  21. .\"========== Put string in boldface & surround with quotes
  22. .de qB
  23. \%\*Q\fB\\$1\fP\*U\\$2
  24. ..
  25. .\"========== 11 on 13 looks so much better than 10 on 12
  26. .nr PS 11
  27. .nr VS 13
  28. .ps 11
  29. .vs 13p
  30. .nr PI 0.5i
  31. .nr HM 0.9i
  32. .nr FM 0.9i
  33. .if n .nr PO 0.5i
  34. .if n .nr LL 6.5i
  35. .\"========== Turn hyphenation off, and make sure it stays off
  36. .nh
  37. .rm hy
  38. .\"========== Headers in italics helps them to stand out from the text
  39. .OH '\fIXvi Source Code Notes\fP''\fI%\fP'
  40. .EH '\fI%\fP''\fIXvi Source Code Notes\fP'
  41. .OF '\fI25th September 1992\fP''\fIPage %\fP'
  42. .EF '\fIPage %\fP''\fI25th September 1992\fP'
  43. .\"===========================================================================
  44. .TL
  45. Notes on the Xvi Source Code
  46. .AU
  47. Chris Downey
  48. John Downey
  49. .AB no
  50. \fBXvi\fP (pronounced \fIecks-vee-eye\fP)
  51. is a free, portable, multi-window implementation of the popular
  52. .UX
  53. editor \fBvi\fP.
  54. .LP
  55. This document contains information on how
  56. to port \fBxvi\fP to systems not currently supported.
  57. It also explains
  58. how the \fBxvi\fP source code is arranged into modules,
  59. and explains some of the data structures which are used,
  60. so that modifications may be made if and when necessary
  61. to the editor itself.
  62. .AE
  63. .\"===========================================================================
  64. .NH 1
  65. INTRODUCTION
  66. .LP
  67. \fBXvi\fP is intended to be portable to just about any system.
  68. This is one of the central reasons for its existence; the
  69. authors wish to be able to use the same editor everywhere.
  70. .LP
  71. The main body of the editor is (supposedly) fully portable,
  72. relying only on standard facilities defined by the White
  73. Book, and on a set of \fIprimitives\fP which are provided by a set
  74. of one or more modules for each operating system.
  75. If
  76. .B __STDC__
  77. is defined, certain ANSI C facilities will be used,
  78. but the editor will compile with non-ANSI compilers.
  79. .LP
  80. Therefore, in order to port \fBxvi\fP to a new system, all that is
  81. necessary is to provide the defined set of \fIprimitives\fP, and
  82. then build the editor.
  83. Or at least, that's the idea; we have refined the set of primitives
  84. as we port the editor to new environments, and it's getting pretty easy now.
  85. .LP
  86. The rest of this document is divided into sections as follows:
  87. .IP "\fISection 2: System-Specific Modules\fP"
  88. This section deals with the layout of source files and makefiles
  89. which you will have to deal with when porting \fBxvi\fP.
  90. .IP "\fISection 3: Primitives Provided by xvi\fP"
  91. Discusses what primitives are provided by the main body of the editor source
  92. code for use by the system interface code.
  93. .IP "\fISection 4: System Interface\fP"
  94. Explains the primitives which need to be provided
  95. in order to make \fBxvi\fP work.
  96. .IP "\fISection 5: Data Structures\fP"
  97. Details the internal data types used in the editor,
  98. and any functions available for operating on those types.
  99. .IP "\fISection 6: Source Files\fP"
  100. Lists the source files comprising the editor,
  101. and explains what functionality is provided by each one.
  102. .\"===========================================================================
  103. .NH 1
  104. SYSTEM-SPECIFIC MODULES
  105. .LP
  106. The system-specific code normally consists of three (or more) files;
  107. a
  108. .qB .c
  109. file, a
  110. .qB .h
  111. file, and a makefile.
  112. For example:
  113. .DS
  114. .B
  115. qnx.c
  116. qnx.h
  117. makefile.qnx
  118. .R
  119. .DE
  120. comprise the system-specific module for the QNX operating system.
  121. .LP
  122. In most cases, the system-specific code is divided into two
  123. or more modules, where one (called the \fIsystem interface module\fP)
  124. is concerned with general interactions with the operating system
  125. and the other (called the \fIterminal interface module\fP)
  126. is designed for a specific interface to a display and keyboard
  127. (and possibly, a mouse).
  128. .LP
  129. For example, the generic
  130. .UX
  131. implementation has
  132. .B unix.c
  133. and
  134. .B unix.h
  135. for the system interface module, and
  136. .B termcap.c
  137. and
  138. .B termcap.h
  139. for the terminal interface module; this should
  140. work reasonably with any full-duplex terminal that can be
  141. described in the
  142. .B termcap
  143. database.
  144. On consoles with memory-mapped displays, or systems with graphic user
  145. interfaces, however, it may be possible to achieve faster
  146. display updating, and perhaps other benefits, by replacing
  147. the
  148. .B termcap
  149. module with another one that makes better use of
  150. whatever facilities are available.
  151. For instance, there is an experimental version for SunView,
  152. which allows mouse input on Sun workstations running the SunView window system.
  153. .LP
  154. On the other hand, the
  155. .B termcap -specific
  156. routines might
  157. conceivably be useful on some other operating systems (such
  158. as VMS), so in general it seemed a good idea to make the
  159. .B termcap -specific
  160. routines a separate module.
  161. .LP
  162. The current \%MS-DOS implementation has a separate terminal
  163. interface module, which is designed specifically for IBM PC
  164. compatible computers.
  165. This is in the files
  166. .DS
  167. .B
  168. ibmpc_a.asm
  169. ibmpc_c.c
  170. ibmpc.h
  171. .R
  172. .DE
  173. The first of these is written in assembly language because
  174. there are not enough routines common to the various \%MS-DOS
  175. C compilers which reliably access the display and keyboard at
  176. a low enough level.
  177. .LP
  178. The hardware-independent system interface module for \%MS-DOS is in
  179. .DS
  180. .B
  181. msdos_a.asm
  182. msdos_c.c
  183. msdos.h
  184. .R
  185. .DE
  186. The first of these is written in assembly
  187. language for the same reason as is
  188. .B ibmpc_a.asm .
  189. .LP
  190. Theoretically, different terminal interface modules could be
  191. written for \%MS-DOS systems running on hardware which is not
  192. IBM-compatible but, unfortunately, such systems seem to be
  193. virtually extinct nowadays.
  194. .LP
  195. Sometimes more than one makefile is provided, as in the case of
  196. .UX ,
  197. where different versions work in slightly different ways.
  198. .LP
  199. It is, of couse, not necessary to provide all \(em or any \(em
  200. of these files for a particular implementation; this is just a convention.
  201. The makefile(s) for each system determine what
  202. files are used in the compilation of the editor.
  203. .LP
  204. The following porting modules are available at present:
  205. .\" ----------------------------------------------------------
  206. .\" Note: this table does not fit very well with nroff output,
  207. .\" so please try to avoid widening it if you add anything.
  208. .TS
  209. center, box;
  210. c|c|c
  211. l|l|l.
  212. System    Makefile    Source Files
  213. _
  214. .sp 0.5v
  215. UNIX
  216.   BSD    \fBmakefile.bsd\fP    \fBunix.[ch] termcap.[ch]\fP
  217.   System V \fB\(dg\fP    \fBmakefile.usg\fP    \fBunix.[ch] termcap.[ch]\fP
  218.   AIX    \fBmakefile.aix\fP    \fBunix.[ch] termcap.[ch]\fP
  219.   ULTRIX    \fBmakefile.ult\fP    \fBunix.[ch] termcap.[ch]\fP
  220.   Xenix \fB\(dg\fP    \fBmakefile.xen\fP    \fBunix.[ch] termcap.[ch]\fP
  221.   POSIX (e.g. BSDI)    \fBmakefile.pos\fP    \fBunix.[ch] termcap.[ch]\fP
  222.   SunOS    \fBmakefile.sun\fP    \fBunix.[ch] termcap.[ch]\fP
  223.   SunView    \fBmakefile.sv\fP    \fBunix.[ch] sunview.h\fP
  224.         \fBsunfront.c sunback.c\fP
  225.         \fBxvi.icn\fP
  226. .sp 0.5v
  227. _
  228. .sp 0.5v
  229. \%MS-DOS        \fBmsdos_c.c msdos.h\fP
  230.         \fBibmpc_c.c ibmpc.h\fP
  231. .sp 0.5v
  232.   Microsoft C 5.*    \fBmakefile.msc\fP    \fB8086mm.inc ibmpc_a.asm\fP
  233.   & MASM 5.*        \fBmsdos_a.asm\fP
  234. .sp 0.5v
  235.   Microsoft Quick C    \fBmakefile.qc\fP    \fB8086mm.inc ibmpc_a.asm\fP
  236.   & MASM 5.*        \fBmsdos_a.asm\fP
  237. .sp 0.5v
  238.   Zortech C++ 2.*    \fBmakefile.zc2\fP    \fB8086mm.inc ibmpc_a.asm\fP
  239.   & MASM 5.*        \fBmsdos_a.asm\fP
  240. .sp 0.5v
  241.   Zortech C++ 3.*    \fBmakefile.zc3\fP    \fB8086mm.inc ibmpc_a.asm\fP
  242.   & MASM 5.*        \fBmsdos_a.asm\fP
  243. .sp 0.5v
  244.   Zortech C++ 3.*
  245.   386 protected mode    \fBmakefile.386\fP    \fBpc386.[ch]\fP
  246. .sp 0.5v
  247. _
  248. .sp 0.5v
  249. OS/2 \fB\(dg\fP
  250.   Version 1, text mode
  251.   Microsoft C 5.1    \fBmakefile.os2\fP    \fBos2vio.[ch]\fP
  252.   & MASM 5.1        \fBi286.asm\fP
  253. .sp 0.5v
  254. _
  255. .sp 0.5v
  256. QNX
  257.   Version 2/3 (CII)    \fBmakefile.qnx\fP    \fBqnx.[ch]\fP
  258.   Version 4 (Watcom C)    \fBmakefile.qn4\fP    \fBunix.[ch] termcap.[ch]\fP
  259. .sp 0.5v
  260. _
  261. .sp 0.5v
  262. TOS \fB\(dg\fP
  263.   Lattice C    \fBmakefile.tos\fP    \fBtos.[ch] tos.lnk\fP
  264. .sp 0.5v
  265. .TE
  266. .IP \fB\(dg\fP 2
  267. Versions marked with
  268. .B \(dg
  269. probably do not work, as systems
  270. have not been recently available to the authors for testing.
  271. .\"===========================================================================
  272. .NH 1
  273. PRIMITIVES PROVIDED BY XVI
  274. .NH 2
  275. General Definitions
  276. .LP
  277. The file
  278. .B xvi.h
  279. should be included by all sys